home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / SOUND / SOUNDCON00 / !SoundCon / Docs / PlaySample < prev   
Text File  |  1995-02-18  |  10KB  |  223 lines
  1.  
  2. The PlaySample module version 2.41
  3. ==================================
  4.  
  5. by Rick Hudson,
  6. rick@actrix.gen.nz
  7.  
  8.  
  9. The PlaySample module is a module that can play samples in a variety of
  10. formats straight from the disc file. It is designed to play samples
  11. accurately at their recorded rate independantly of current sound system
  12. speed and (hopefully) the effects of VIDC enhancers.
  13.  
  14. The PlaySample module provides a small number of commands and a few SWIs
  15. that can be used to control the playback of samples. It's usual use will be
  16. from the desktop through a program like SoundCon or MTaudio. Command line
  17. use is quite limited as it can only play Armadeus files.
  18.  
  19. Terminology notes for this text:
  20.  
  21.   - A "sample" is the wave amplitude at a given time for ONE given channel
  22.  
  23.   - A "sample frame" or just "frame" is the set of samples on ALL channels
  24.     at a given time. For a mono sound this will mean the same as a sample,
  25.     but for a stereo sound there are two samples per sample frame (one for
  26.     each channel)
  27.  
  28.   - A "sample file" is the disc file containing samples
  29.  
  30.   - "Sample period" is the time interval between sending sample frames to
  31.     the sound system
  32.  
  33.   - "Sample frequency" or "playback frequency" is the rate of sending
  34.     sample frames to the sound system. The actual number of bytes per
  35.     second will depend on the bits per sample and the number of channels.
  36.  
  37.  
  38. Commands:
  39.  
  40.   - SPlay <filename> [<start>]
  41.  
  42.       Start playing the sound in file <filename>. Optionally, the sound
  43.       can be started at byte offset <start>. Note that if manual polling is
  44.       enabled then *SMore must be used regularly to maintain playback. The
  45.       sound must be an Armadeus format file otherwise unpredicable things
  46.       will happen. Playing of other formats is only supported through the
  47.       SWI interface.
  48.  
  49.   - SStop
  50.  
  51.       Stop the sound playing and release the sound system.
  52.  
  53.   - SPause
  54.  
  55.       Toggle start/stop of sound playback.
  56.  
  57.   - SMore
  58.  
  59.       In manual polling mode, this command must be executed regularly (say
  60.       twice a second at least) to maintain playback continuity. If the
  61.       buffer 'runs out' then the sound is stopped (equivalent to an
  62.       explicit *SPause) until the buffer is refilled. This command has no
  63.       effect in automatic polling mode or when no sound is playing.
  64.  
  65.   - SAuto
  66.  
  67.       Switch on automatic polling (see below).
  68.  
  69.   - SManual
  70.  
  71.       Switch off automatic polling (see below).
  72.  
  73.   - SVolume <vol>
  74.  
  75.       Set the volume of PlaySample. <vol> is in the range 1 (quiet) to 127
  76.       (loud), the same the system *Volume command. Note that PlaySample uses
  77.       a volume setting independant of the system volume so that *Volume will
  78.       have no effect on it.
  79.  
  80.   - SSpeed <num>
  81.  
  82.       <num> is a tuning value for PlaySample to allow for the correction of
  83.       playback speed when the actual VIDC frequency is different from what
  84.       the sound system is expecting. <num> is <expected freq>/<actual freq>
  85.       * &10000, eg 24000/25175*&10000 = 62447 will slow the sound down
  86.       sightly if it is too fast. The actual frequency can be obtained from
  87.       VduVariable &AC in RISC OS (except if it's very old) and the expected
  88.       frequency is the nearest multiple of 4000Hz to it. Desktop front ends
  89.       should select this automatically.
  90.  
  91. SWIs:
  92.  
  93.   PlaySample_Status (&CF8C0)
  94.     Playback monitors can use this call to determine what the state of the
  95.     player is. R2, R4 and R5 can be used to determine the time offset into
  96.     the sample using t=R2 / (16e6/R4) / (bits per sample/8*channels).
  97.     On entry: -
  98.     On Exit:  R0 : bit  0 = set if sound is playing
  99.                    bit  1 = set if sound paused
  100.                    bit  2 = set if sound finished
  101.                    bit  3 = set if a sound file is open
  102.                    bit  4 = set if module has voice claimed
  103.                    bit 31 = set if manual polling enabled
  104.               R1 = pointer to file leafname
  105.               R2 = current byte offset into sample file
  106.               R3 = size of sample file in bytes
  107.               R4 = sample period (microseconds * 16)
  108.               R5 = voice mode: bit 0 = set if stereo, clear if mono
  109.                                bits 1-7: 0 = 8-bit
  110.                                          1 = 16-bit
  111.                                          2 = 4-bit MS ADPCM
  112.                                          3 = 4-bit DVI ADPCM
  113.  
  114.   PlaySample_Open (&CF8C1)
  115.     Open a file and define its format. Playback is not started (pause mode
  116.     is entered). Use PlaySample_Play to start the playback.
  117.     On entry: R0 = pointer to filename to open (0 for current file)
  118.               R1 = sample format:
  119.                    <=0 - 8 bit linear signed
  120.                      1 - 8 bit linear unsigned
  121.                      2 - 8 bit mu-law
  122.                      3 - 8 bit VIDC
  123.                      4 - 16 bit linear signed little endian
  124.                      5 - 16 bit linear signed big endian
  125.                      6 - 16 bit linear unsigned little endian
  126.                      7 - 16 bit linear unsigned big endian
  127.                      8 - Microsoft ADPCM
  128.                      9 - DVI ADPCM
  129.               R2 = sample period in microseconds * 16 (if R2=0 and R1=-1,
  130.                    period obtained from first byte of file). eg for 22050Hz,
  131.                    R2=16e6/22050 = 727. Default frequency (if R2 is invalid)
  132.                    is 11111Hz.
  133.               R3 = number of channels (<>2 for mono, 2 for stereo).
  134.               R4 = file offset of last sample to play + 1. If the file has
  135.                    'garbage' after the actual sound sample then pointing R4
  136.                    at the first garbage byte will define the end point. If
  137.                    R4<=0 playback stops when the end of the file is reached.
  138.               if R3<>2 (mono) then
  139.                  R5 = echo delay in sample periods for simulated stereo
  140.                       effect (max 2048). R5=(echo time)*(playfrequency), eg
  141.                       R5 = 0.1secs * 11111Hz = 1111.
  142.               if R3=2 (stereo) then
  143.                  R5 = stereo interleave (bytes left, bytes right, etc). eg 1
  144.                       for PCM WAVEs, 8 for AudioWorks. This number must be a
  145.                       power of 2 (ie 1, 2, 4, 8, etc) and the buffer size
  146.                       must be a multiple of 2*interleave to ensure that a
  147.                       left/right chunk is always completely in the buffer.
  148.               if R1=8 or 9 (ADPCM formats) then
  149.                  R6 = number of compressed sample frames in block. ie
  150.                       nFramesPerBlock (bytes &12 and &13 of the WAVE 'fmt '
  151.                       chunk) - frames in block header. ie nFramesPerBlk-1
  152.                       for DVI ADPCM and nFramesPerBlock-2 for MS ADPCM.
  153.  
  154.     This call will require knowledge of the file format to fill in all the
  155.     registers properly. ADPCM WAVEs in particular need precise information
  156.     from the header block. Contact the author if you want more information
  157.     on any of the formats supported by SoundCon or if you can supply some
  158.     information on any formats it doesn't support!
  159.  
  160.     Note that to play a normal armadeus sample at the default frequency,
  161.     R1=-1, R2=R3=R4=0.
  162.  
  163.   PlaySample_SetPtr (&CF8C2)
  164.     On entry: R0 = absolute file offset to move to. Used to set the start
  165.     position after the file header or for cueing etc.
  166.  
  167.   PlaySample_Play (&CF8C3)
  168.     Start playing the sound from the current pointer position.
  169.  
  170.   PlaySample_Stop (&CF8C4)
  171.     If a sound is playing, it is stopped and the sound system is freed. No
  172.     more playback will be possible until another PlaySample_Open is done. 
  173.  
  174.   PlaySample_Pause (&CF8C5)
  175.     Stop the sound playing but playback can be restarted with
  176.     PlaySample_Play. PlaySample_SetPtr can be called while paused.
  177.  
  178.   PlaySample_Config (&CF8C6)
  179.     On entry: R0 = buffer size (0 for no change - default is 8k)
  180.               R1 = polling: 0 = no change, 1 = automatic, 2 = manual
  181.     On exit:  R0 = buffer size
  182.               R1 = polling mode
  183.  
  184.     Important note: For playing ADPCM samples, the buffer size MUST be a
  185.     multiple of the sample block size. ie size = n*nBlockAlign. For other
  186.     samples, the buffer must be a multiple of the number of bytes per frame.
  187.     eg for 16 bit stereo, the buffer must be a multiple of 4 bytes.
  188.  
  189.   PlaySample_Volume (&CF8C7)
  190.     Set or read the PlaySample volume. Note that PlaySample's volume is
  191.     independant of the system volume. 
  192.     On entry: R0 = volume (0 for no change, 1=quiet, 127=loud)
  193.     On exit:  R0 = volume setting
  194.  
  195.   PlaySample_Speed (&CF8C8)
  196.     Tune Playsample for sound system speed inaccuracies. See the description
  197.     of *SSpeed (above) for details.
  198.     On entry: R0 = tuning value (<expected freq> / <actual freq> * &10000)
  199.     On exit:  R0 undefined
  200.  
  201.   PlaySample_Version (&CF8C9)
  202.     Return the version number*100 of PlaySample (241 for version 2.41)
  203.     On entry: -
  204.     On exit:  R0 = version number * 100
  205.     
  206. Note that it is not necessary to stop a sample playing before starting a new
  207. one or killing the module.
  208.  
  209. Polling mechanism: The normal polling mechanism makes use of OS_AddCallBack
  210. to allow delayed access to disc SWIs from inside the voice generator code.
  211. This may cause problems in RISC OS 2 (although this version seems ok) where
  212. there was a bug in the call back handler. If errors start occurring (like
  213. address exceptions) then first ensure that the IRQUtils module has been
  214. loaded which should fix this problem. If the PlaySample module is still
  215. causing problems then manual polling can be used (software may or may not
  216. allow you to change this).
  217.  
  218. If the sample stops unexpectedly when playing off a floppy disc, try either
  219. decreasing the buffer size to keep the drive running continuously or
  220. increase it to ensure that enough data is in the memory to cover the time it
  221. takes to restart the floppy from a stop. This is a trial and error thing!
  222.  
  223.